Skip to content

README: clarify tables.create vs tables.load - #96

Open
jirkasemmler wants to merge 1 commit into
masterfrom
readme-clarify-create-vs-load
Open

jirkasemmler wants to merge 1 commit into
masterfrom
readme-clarify-create-vs-load

Conversation

@jirkasemmler

Copy link
Copy Markdown
Contributor

Why

#84 reports a conflict between the README (tables.create under a generic "save data" comment) and the developer docs (tables.load). Both are correct, they just do different things and the README did not say so.

What

Replace the "save data" example with explicit examples for:

  • tables.create – create a new table from a CSV file
  • tables.load – load data into an existing table, full or incremental

Fixes #84

🤖 Generated with Claude Code

The README only showed tables.create under a generic "save data"
comment, while the developer docs show tables.load. Both are correct
but do different things: create makes a new table from a CSV file,
load imports data into an existing table (full or incremental).
Show both so the two documents no longer look contradictory.

Fixes #84

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@jirkasemmler
jirkasemmler requested review from a team and martinsifra and removed request for a team September 29, 2026 08:36

@martinsifra martinsifra left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review summary

This docs-only change fixes #84. It replaces the vague # save data comment in both README usage blocks with explicit tables.create (new table) and tables.load (existing table, full or incremental) examples.

  • Every documented call matches the current signatures: create at kbcstorage/tables.py:74, load at :209.
  • The table id and file path in the load examples line up with the preceding create and export_to_file calls.
  • The load semantics in the comments match the Storage docs (Incremental Loading).
  • The branch is behind master (#94), but it merges cleanly, and the merged README reads fine next to the new StorageApiToken examples.

No blockers. Two optional wording nits.

Nits

1. The two usage blocks describe is_incremental differently. The lines are README.md:61 and README.md:31-35.

  • The client-class block says incremental means "append rows / upsert by primary key".
  • The endpoint-class block says is_incremental=True means "append instead of replace". That is only true for tables without a primary key.
  • Same flag, two descriptions: the kind of README-vs-README mismatch #84 was about.

Suggested wording, the same in both blocks:

# load data into an existing table (full load truncates the table first)
# ... is_incremental=True appends rows, or upserts them if the table has a primary key

2. The create example has no primary key, so the upsert case never applies (README.md:28-35).

  • some-table-2 is created without primary_key, so the incremental load right after it only appends.
  • Optionally show primary_key=['id'], as the developer docs do.
  • Optionally also say that create fails when the table already exists. That is the other half of create vs load.
  • The current text is not wrong.

Notes, not blocking

  • The failing Run tests (AWS/Azure/GCP) checks are pre-existing.
    • Master fa5df8e fails the same tests/functional/test_tables.py cases on all three stacks: buckets.create 400 in setUp, Application error jobs, bucket not found in tearDown.
    • A README-only diff cannot cause them. The build and mock tests pass.
  • Pre-existing bug, out of scope for this PR: Tables.load(columns=[...]) has no effect.
    • load_raw sends the list as primaryKey[] (kbcstorage/tables.py:292-293). The Storage import-async endpoint reads it as columns and ignores unknown parameters, so the column list is dropped silently, e.g. together with without_headers=True.
    • The README doesn't document columns=, so this is unrelated to this change. It's worth a separate issue or PR.

@martinsifra martinsifra left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This docs-only change fixes #84. It replaces the vague # save data comment with explicit tables.create (new table) and tables.load (existing table, full and incremental) examples.

  • Every documented call matches the current signatures.
  • The load semantics match the Storage docs.
  • The branch merges cleanly with current master.

No blockers. The two optional wording nits are in the review above. The red CI is pre-existing on master and unrelated.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

documentation conflict?

2 participants